node-powertools

Site | NPM Module | GitHub Repo

Node Powertools is an NPM module for backend and frontend developers that exposes powerful utilities and tools.

🌐 Node Powertools Works in Node AND browser environments

Yes, this module works in both Node and browser environments, including compatibility with Webpack and Browserify!

🦄 Features

• Useful randomization tools to mix things up
• Helpful polling utilities to wait for variables or events
• Powerful regexify and escape functions to go work with RegExp

📦 Install Node Powertools

Option 1: Install via npm

Install with npm if you plan to use Node Powertools in a Node.js project or in the browser.

npm install node-powertools

If you plan to use node-powertools in a browser environment, you will probably need to use Webpack, Browserify, or a similar service to compile it.

const powertools = require('node-powertools');

Option 2: Install via CDN

Install with CDN if you plan to use Node Powertools only in a browser environment.

<script src="https://cdn.jsdelivr.net/npm/node-powertools@latest/dist/index.min.js"></script>
<script type="text/javascript">
  var powertools = Powertools(); // The script above exposes the global variable 'Powertools'
</script>

⚡️ Usage

powertools.random(min, max, options)

Generate a random number between two numbers min and max. You can use options to supply a sign or randomize the sign as well. If an array is supplied, a random element from the array is returned. The default options.mode is uniform but you can also supply gaussian which will generate random values on a gaussian bell curve.

powertools.random(0, 100, {mode: 'uniform'}); // Possible output: 69
powertools.random(-100, 100, {mode: 'uniform'}); // Possible output: -69
powertools.random(-100, 100, {mode: 'gaussian'}); // Possible output: -69
powertools.random(['Apple', 'Orange', 'Pear']); // Possible output: Orange (random element)

powertools.arrayify(input)

Transform the input into an array if it is not already.

powertools.arrayify(1); // Output: [1]
powertools.arrayify([1]); // Output: [1]

powertools.wait(time)

Asynchronously wait for the specified time in milliseconds.

await powertools.wait(1000); // waits for 1000 ms (1 second)

powertools.poll(fn, options)

Asynchronously wait for the specified fn to return true. You can use options to supply a polling interval and timeout in milliseconds. The promise rejects if the timeout is reached.

// Call this function every 100 ms until it returns true or 30000 ms passes
await powertools.poll(function (index) {
  return something === somethingElse;
}, {interval: 100, timeout: 30000});

powertools.queue(options)

Returns a Queue which you can run .add(fn) where fn is an Asynchronous function. The queue will process the functions in FIFO (first in, first out) order and will only process the next async function after the one before it resolves or rejects.

// Queue options
const options = {
  delay: 100, // Delay between each function in milliseconds
}

// Create the queue
const queue = powertools.queue(options)

// Queue the first function
queue.add(async () => {
  console.log('Queue 1 started');
  await powertools.wait(1000)
  console.log('Queue 1 finished');
})

// Queue the second function
// This will only begin executing after the first function completes
queue.add(async () => {
  console.log('Queue 2 started');
  await powertools.wait(1000)
  console.log('Queue 2 finished');
})

powertools.getPromiseState(promise)

Returns pending, resolved, or rejected based on the state of the promise. This is useful for checking if a promise has been resolved or rejected.

This method depends on util from Node.js, so it will not work in the browser.

const promise = new Promise((resolve, reject) => {
  setTimeout(() => {
    resolve('done');
  }, 1000);
});

powertools.getPromiseState(promise); // Output: 'pending'
await promise;
powertools.getPromiseState(promise); // Output: 'resolved'

powertools.waitForPendingPromises(promises, options)

Wait for options.max promises to resolve before continuing. This is useful for when you have a large number of promises and you want to limit the number of concurrent promises that are running at any given time. This promise rejects if the options.timeout is reached.

This method depends on util from Node.js, so it will not work in the browser.

const promises = [
  powertools.wait(1000),
  powertools.wait(2000),
  powertools.wait(3000),
];

console.log('Starting processing', promises);

await powertools.waitForPendingPromises(promises, {max: 2, timeout: 2000});

console.log('Finished processing', promises);

powertools.escape(str)

Add the escape character \ before any character in str that needs to be escaped for a RegExp.

powertools.escape('*'); // Output: \*
powertools.escape('/'); // Output: \/
powertools.escape('\\'); // Output: \\
powertools.escape('.$^'); // Output: \.\$\^

powertools.regexify(str)

Revive a str into a RegExp. Supports flags. Depending on how you want special characters to be treated, you can use powertools.escape(str) prior to using powertools.regexify(str).

powertools.regexify('/Apple/'); // Output: RegExp /Apple/
powertools.regexify('/Apple/i'); // Output: RegExp /Apple/i
powertools.regexify('Apple'); // Output: Throws error (needs to start and end with /)
powertools.regexify('/Apple/x'); // Output: Throws error (x is not a valid flag)

powertools.regexify('/Ap.le/'); // Output: RegExp /Ap.le/
powertools.regexify(`/${powertools.escape('Ap.le')}/`); // Output: RegExp /Ap\.le/

powertools.timestamp(date, options)

Convert a date to a timestamp in 3 formats: an ISO string, a UNIX number, or a plain-ol' JS Date (as specified in options). The first argument date can be a JS Date, a UNIX timestamp number, or a string that will be parsed by the new Date() method.

powertools.timestamp(new Date('2999/12/31'), {output: 'string'}); // Output: "2999-12-31T08:00:00.000Z"
powertools.timestamp(new Date('2999/12/31'), {output: 'unix'}); // Output: 32503622400
powertools.timestamp(new Date('2999/12/31'), {output: 'date'}); // Output: Tue Dec 31 2999 00:00:00 GMT-0800 (Pacific Standard Time)

powertools.timestamp(32503622400, {output: 'string'}); // Output: "2999-12-31T08:00:00.000Z"
powertools.timestamp(32503622400, {output: 'unix'}); // Output: 32503622400
powertools.timestamp(32503622400, {output: 'date'}); // Output: Tue Dec 31 2999 00:00:00 GMT-0800 (Pacific Standard Time)

powertools.force(value, type, options)

Intelligently converts a value to a type how JavaScript should. The acceptable types are string, number, boolean, array. This is useful for helping to validate user input, such as considering 'true' (string) to be true (boolean) or '0' (string of a number) to be false (boolean).

powertools.force('true', 'boolean'); // Output: true
powertools.force('false', 'boolean'); // Output: false
powertools.force('0', 'boolean'); // Output: false
powertools.force('1,2,3', 'array'); // Output: ['1', '2', '3']
powertools.force('1,2,3', 'array', {force: 'number'}); // Output: [1, 2, 3]
powertools.force(undefined, 'string'); // Output: ''

powertools.defaults(settings, defaults)

Easily structure your settings object by validating them with a defaults object. This function automatically fills in any missing keys in settings with the corresponding key in defaults, removes any keys in settings that are not in defaults, and converts any values in settings to the same type as the corresponding key in defaults.

How to Define Defaults

• types: An array of valid types for the value.
• default: Any value that will be used if the key is missing.
• min: A number limiting the minimum value if the value is a number, or the minimum length if the value is a string.
• max: A number limiting the maximum value if the value is a number, or the maximum length if the value is a
• value: Any value that will override the value in settings regardless of what it is (force the value).

const defaults = {
  name: {
    types: ['string'],
    default: '',
    min: 0,
    max: 10,
  },
  stats: {
    level: {
      types: ['number'],
      default: 1,
      min: 1,
      max: 2,
    },
    index: {
      value: 1,
    },
  },
}
powertools.defaults({}, defaults); // Output: {name: '', stats: {level: 1}}
powertools.defaults({name: 'What a long name!'}, defaults); // Output: {name: 'What a lon', stats: {level: 1}}
powertools.defaults({stats: {level: 3}}, defaults); // Output: {name: '', stats: {level: 2}}

powertools.getKeys(obj)

Walk through any obj and get an array of every key, including nested keys.

powertools.getKeys({name: 'Jon Snow'}); // Output: ['name']
powertools.getKeys({name: 'Jon Snow', favorites: {color: 'red'}}); // Output: ['name', 'favorites.color']
powertools.getKeys({}); // Output: []

powertools.isObject(obj)

Check if obj is a good ol... object. In JavaScript, null is, unfortunately, considered an object. This function does not consider null to be an object.

powertools.isObject({}); // Output: true
powertools.isObject(null); // Output: false

powertools.stringify(obj)

Stringify an obj into a JSON string even if it has circular references.

powertools.strigify({}); // Output: '{}'

powertools.template(str, data)

Replace all instances of {key} in str with the corresponding value in data.

powertools.template(
  'My favorite color is {color}',
  {color: 'purple'}
); // Output: 'My favorite color is purple'
powertools.template(
  'Ian\'s favorite color is {ian.color}',
  {ian: {color: 'purple'}
); // Output: 'Ian\'s favorite color is purple'

powertools.uniquify(arr)

Return an array arr with all duplicates removed.

powertools.uniquify([{id: 1}, {id: 1}, {id: 2}]); // Output: [{id: 1}, {id: 2}]

powertools.iterate(arr, callback)

Asynchronously iterate through an array arr and call callback on each element. This function is useful for when you need to wait for asynchronous functions to complete before moving on to the next element in the array.

const sampleArray = [1, 2, 3, 4, 5];

// Simulate an async operation like a database call
const asyncTask = (item, index) => {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      console.log(`Processing item ${item} at index ${index}`);
      return resolve();
    }, 1000);
  });
};

// Process each item in the array asynchronously
Powertools.iterate(sampleArray, asyncTask)
  .then(() => console.log('All tasks completed.'));

powertools.execute(command, options, setupCallback)

Asynchronously execute a command in the terminal. This function is useful for when you need to run a command in the terminal and wait for it to complete before moving on to the next step in your code.

// Run a simple command
await powertools.execute('ls -a')
.then((output) => {
  console.log('Files:', output);
})

// Run a command with config
await powertools.execute('ls -a', {
  config: {cwd: '/path/to/directory'},
})
.then((output) => {
  console.log('Files:', output);
})

// Run a command with options like options.log
// This will write the command's output to process.stdout and process.stderr
// This is useful if you're running an intensive command and want to see the output in real-time
await powertools.execute('ls -a', {
  log: true,
})
.then((output) => {
  console.log('Files:', output);
})

// Run with a setupCallback
await powertools.execute('ls -a', {
  log: true,
}, (child) => {
  console.log('Child process:', child);
})
.then((output) => {
  console.log('Files:', output);
})

powertools.whitelist(obj, keys)

Return a new object with only the keys in keys from obj.

powertools.whiteList({name: 'Jon Snow', age: 25}, ['name']); // Output: {name: 'Jon Snow'}

powertools.hyphenate(str, options)

Convert a str to hyphenated case. You can use options to customize the hyphenation.

powertools.hyphenate('Jon Snow'); // Output: 'jon-snow'
powertools.hyphenate('Jon Snow', {lowercase: false}); // Output: 'Jon-Snow'
powerTools.hyphenate('Jon Snow!', {removeNonAlphanumeric: true}); // Output: 'jon-snow'

🗨️ Final Words

If you are still having difficulty, we would love for you to post a question to the Node Powertools issues page. It is much easier to answer questions that include your code and relevant files! So if you can provide them, we'd be extremely grateful (and more likely to help you find the answer!)

📚 Projects Using this Library

Somiibo: A Social Media Bot with an open-source module library.
JekyllUp: A website devoted to sharing the best Jekyll themes.
Slapform: A backend processor for your HTML forms on static sites.
Proxifly: A backend processor for your HTML forms on static sites.
SoundGrail Music App: A resource for producers, musicians, and DJs.
Hammock Report: An API for exploring and listing backyard products.

Ask us to have your project listed! :)